ice-web-components 1.0.0 → 1.2.0

package/README.md

@@ -27,31 +27,24 @@ rings and shadows) is drawn by the engine.
 - **Bootstrap 5 token theme** (plus a dark theme) — swap with one call.
 - **No name collisions with the engine** — the package’s runtime exports are
   disjoint from `ice-render`’s (there is a regression test for it).
-- **Actually tested** — 705 unit tests (98 suites: form validation, overlay
+- **Actually tested** — 749 unit tests (101 suites: form validation, overlay
   positioning, keyboard navigation, sort/hover/focus edge cases, the Minesweeper,
-  Tetris and Snake rule models) plus five browser QA suites (`qa:admin`, `qa:gallery`,
-  `qa:workbench`, `qa:xp`, `qa:arcade` — 198 assertions) that drive the demo pages with
+  Tetris, Snake, 2048 and CHIP-8 rule/machine models, the pixel canvas and the undo
+  stack) plus six browser QA suites (`qa:admin`, `qa:gallery`, `qa:workbench`, `qa:xp`,
+  `qa:arcade`, `qa:pixel` — 232 assertions) that drive the demo pages with
   real mouse and keyboard events and fail on any console error.
 
 ## Quick start
 
-> **Install**: `1.0.0` is the first tagged release. The engine (`ice-render`) is on npm;
-> the component library ships as a tarball / git dependency for now — use one of the following:
+> **Install**: both packages are on npm now — `npm install ice-web-components` (it pulls
+> `ice-render` as a dependency). `1.0.0` is the first published release; from a checkout you
+> can also `npm install /path/to/ice-web-components` or `npm install git+https://github.com/ice-render/ice-web-components.git`.
 
 ```bash
-# ① a local path (the usual thing inside a monorepo / workspace)
-npm install /path/to/ice-web-components
-
-# ② straight from git
-npm install git+https://github.com/ice-render/ice-web-components.git
-
-# ③ pack it, then install the tarball
-(cd /path/to/ice-web-components && npm pack)     # produces ice-web-components-0.0.1.tgz
-npm install /path/to/ice-web-components-0.0.1.tgz
+npm install ice-web-components   # + ice-render, pulled automatically
 ```
 
-All three pull the `ice-render@^1.3.0` dependency from npm. The published tarball
-contains `dist/` only (cjs + esm + umd + type declarations).
+The published tarball contains `dist/` only (cjs + esm + umd + type declarations).
 
 ```ts
 import { ICE } from 'ice-render';
@@ -224,8 +217,8 @@ that window is active; closing the window stops its step timer.
 
 Not a web page but a **handheld console**: the shell, the screen bezel, the HUD cards,
 the buttons and the sound switch are all ICE components, and there is not a single
-bitmap asset in the picture. Three cartridges are plugged in, and the cartridge row at
-the top switches between them (a fourth slot, Chinese chess, is disabled for now).
+bitmap asset in the picture. Four cartridges are plugged in, and the cartridge row at
+the top switches between them (a fifth slot, Chinese chess, is disabled for now).
 
 | | |
 |---|---|
@@ -256,10 +249,32 @@ weight and text colour, so a 4×4 board with 16 numbers is still one node.
 
 ![ICE Arcade · 2048](docs/images/arcade-2048.png)
 
-Both games are pure models that never touch the canvas; the page only reads the model
+**Cartridge 4 — CHIP-8** (`ICEChip8Model`, 19 unit tests). The odd one out: instead of
+“the rules of a game” it is **an actual virtual machine** — 4 KB of memory, `V0`–`VF`,
+the 16-bit `I` register, a 64×32 monochrome framebuffer, two 60 Hz timers and a 16-key
+keypad. 35 opcodes are implemented (`00E0` / `1NNN` / `2NNN` / `DXYN` / `EX9E` / `FX0A` /
+`FX29` / `FX33` / `FX55` …), including `DXYN`’s XOR drawing with the classic
+`VF = collision` flag and `FX0A` blocking key waits.
+
+The console ships a **self-written demo ROM** (no external ROM, no copyright questions):
+it clears the screen, draws an 8×8 smiley, moves it, flips its velocity when a wall is
+reached, and loops — which exercises conditional skips and two’s-complement arithmetic
+as well as drawing. Both the 2048-cell framebuffer and the 4×4 machine keypad are single
+`ICETileMap` nodes; the keys light up while pressed, which makes the `keydown` / `keyup`
+path visible. On that cartridge the machine owns its 16 keys (`1 2 3 4 / Q W E R / A S D F
+/ Z X C V`), so the console hands even `R` to the ROM and keeps `P` for pause.
+
+![ICE Arcade · CHIP-8](docs/images/arcade-chip8.png)
+
+All four games are pure models that never touch the canvas; the page only reads the model
 and paints cells. Switching a cartridge tears the old board down, builds the new one
-and re-captions the HUD, so a third game is a registry entry plus a `mount()`.
-Switching away from the tab pauses whatever is running.
+and re-captions the HUD, so another game is a registry entry plus a `mount()`.
+Switching away from the tab pauses whatever is running (CHIP-8 also drops its pressed
+keys, otherwise a lost `keyup` would leave `FX0A` waiting forever).
+
+| Pause overlay (`已暂停`) |
+|---|
+| ![ICE Arcade paused](docs/images/arcade-paused.png) |
 
 Under the hood this page is where the engine work happens:
 
@@ -279,6 +294,10 @@ Under the hood this page is where the engine work happens:
 - Toasts are **replaced, not stacked**: a console only needs one status line, and the QA
   caught a stack of three toasts covering the cartridge row (the click never reached the
   button). `ICEMessage` still supports stacking for pages that want it.
+- CHIP-8 also drove two engine fixes: an offscreen-cache bug where a bitmap baked the
+  *ancestor’s* opacity (so the pause plate faded in but its “已暂停” text never appeared —
+  translucent subtrees are no longer cached, and stale bitmaps are dropped), and
+  keyboard routing that lets a cartridge declare the keys it owns.
 
 | Leaderboard (`ICEModal` + `ICETable` + `ICEScrollPane`) |
 |---|
@@ -289,6 +308,52 @@ Under the hood this page is where the engine work happens:
 > A game page keeps the keyboard for itself; mouse hover still goes through
 > `ICEHoverManager`.
 
+### `pixel-editor.html` — ICE Pixel Studio (a real pixel editor)
+
+The other direction: instead of “draw a business screen”, this page is a **tool**.
+The canvas, tool palette, colour swatches and status bar are all components — only the
+pixels themselves are self-drawn, as a single `ICETileMap` node. Pencil, eraser, line,
+rectangle and flood fill, undo/redo, and PNG + SVG export.
+
+![ICE Pixel Studio](docs/images/pixel-editor.png)
+
+Two pure models carry it (no canvas involved):
+
+```ts
+import { ICEPixelModel, ICEHistoryModel } from 'ice-web-components';
+
+const model = new ICEPixelModel({ rows: 32, cols: 32, palette: PALETTE, background: 0 });
+model.setPixel(4, 4, 1);        // live change; returns whether it really changed
+model.drawLine(0, 0, 0, 7, 2);  // Bresenham
+model.fill(3, 3, 5);            // 4-neighbour flood fill (iterative, no recursion)
+model.commit();                 // one commit = one undo step
+model.toSVG({ cellSize: 16 });  // run-length merged SVG string
+model.toRGBA(16);               // feed it straight into ImageData for PNG export
+```
+
+The three decisions worth stealing:
+
+1. **History is per *operation*, not per pixel** — a 20-cell drag pushes exactly one
+   snapshot (`mousedown` paints, `mouseup` commits). Otherwise undo would need 20
+   presses to walk one stroke back, which decides whether a 1024-cell editor is usable.
+   `ICEHistoryModel` itself is a plain generic stack (push clears redo, trims to a limit,
+   notifies with a reason) — reusable for kanban or table editing too.
+2. **Preview via the highlight layer, not “draw then undo”** — dragging a line or a
+   rectangle lights up `ICETileMap.setHighlights()` from `getLineCells()` /
+   `getRectCells()`, and only `mouseup` commits. Preview and painting share the same
+   coordinate API, so the preview is exactly what you get (a unit test paints both and
+   compares cell by cell).
+3. **Export is pure** — `toSVG()` merges horizontal runs into single `<rect>`s (the
+   32×32 smiley emits 20 elements, not 1024), and `toRGBA(scale)` hands the page an
+   `ImageData` buffer; only the page touches `canvas.toDataURL()`. The QA asserts on the
+   data: the PNG check decodes the **IHDR** chunk to prove the bitmap is 512×512.
+
+> A component gap this page closed: `ICETileMap` cached `rows`/`cols`/`cellSize` in
+> instance fields, so resizing with only `setState({ rows, cols })` left the internals
+> stale and the next `setTiles` threw (“expected 1024 cells, got 256”). There is now a
+> proper `setSize(rows, cols, cellSize?)` that updates the internals, the state and the
+> default width/height in one go, and clears the old cell data.
+
 ## Components
 
 | Group | Components |
@@ -300,12 +365,12 @@ Under the hood this page is where the engine work happens:
 | Feedback & status | `ICEAlert` `ICEModal` `ICEDrawer` `ICEMessage` `ICENotification` `ICETooltip` `ICEPopover` `ICEPopconfirm` `ICETour` `ICEFloatButton` `ICEEmpty` `ICESkeleton` `ICESpin` `ICEResult` `ICESteps` `ICEOverlayManager` |
 | Navigation | `ICEMenu` `ICEBreadcrumb` `ICEAnchor` `ICEBackTop` `ICEDropdown` `ICEPagination` `ICETabs` |
 | Layout & core | `ICEWidget` `ICEContainer` `ICEHoverManager` `ICEFocusManager` `ICEMessageManager` `ICEManager` (`ICEPainter` / `ICELayoutManager` are types) |
-| Models | `ICEButtonModel` `ICEToggleModel` `ICEBoundedRangeModel` `ICESelectionModel` `ICEFormModel` |
+| Models | `ICEButtonModel` `ICEToggleModel` `ICEBoundedRangeModel` `ICESelectionModel` `ICEFormModel` `ICEHistoryModel` `ICEPixelModel` `ICETetrisModel` `ICESnakeModel` `ICE2048Model` `ICEChip8Model` `ICEMinesweeperModel` `ICEHighScoreModel` |
 
 Helper functions: `attachTooltip` `attachPopover` `attachPopconfirm` `attachDropdown`
 `openModal` `openDrawer` `getICEOverlayManager` `getICEFocusManager` `getICEMessageManager`
 `formatStatisticValue` `formatCountdown` `truncateTextLines` `buildMonthGrid` `formatCalendarDate`
-`openImagePreview` `tween` `fadeIn` `fadeOut` `slideIn` `scaleIn` and friends.
+`openImagePreview` `icePixelParseColor` `tween` `fadeIn` `fadeOut` `slideIn` `scaleIn` and friends.
 
 ## Theme
 
@@ -440,6 +505,11 @@ npm run qa:xp
 # real clicks on the HUD
 npm run qa:arcade
 
+# browser QA for examples/pixel-editor.html: drawing with a real mouse (pencil drag,
+# line/rect preview, flood fill, eraser), undo/redo via buttons and Ctrl+Z/Y, and the
+# PNG (IHDR-checked) / SVG exports
+npm run qa:pixel
+
 # docs: regenerate the API reference and check relative links
 npm run docs
 ```