@21stware/rpui 0.1.0 → 0.2.1

package/llms.txt

@@ -1,6 +1,6 @@
 # RPUI Web Components Reference for LLMs
 
-RPUI means Readable Prototype UI. It is a static prototype specification and rendering runtime implemented with native Web Components.
+RPUI means Rapid Prototype UI. It is a static prototype specification and rendering runtime implemented with native Web Components.
 
 A generated prototype imports one file only:
 
@@ -10,6 +10,8 @@ A generated prototype imports one file only:
 
 `dist/rpui.js` registers all custom elements and injects runtime CSS plus Lucide-style inline SVG icons. Do not import external CSS, image CDNs, icon CDNs, or UI frameworks.
 
+ARIA note: component states (checked / expanded / selected / disabled / current / pressed) follow the structure that the W3C ARIA Authoring Practices expect, so annotations can describe accessibility intent precisely. RPUI is static and does not emit runtime `role` / `aria-*` attributes — treat ARIA as a reference for which states to expose and document, not as runtime behavior.
+
 ## Core model
 
 RPUI has two layers:
@@ -59,6 +61,20 @@ Every `data-pin="N"` must have a matching top-level annotation:
 
 RPUI renders water-drop pins automatically. Never write pin DOM manually.
 
+## Section addressing, deep links, and enum numbering
+
+The runtime makes the canvas navigable. Authors do not write any of these attributes — they are generated:
+
+- Every annotation gets a `data-rp-section` path. Top-level annotations use their `id` (e.g. `3`); nested annotations use the parent path plus their 1-based position among annotation siblings (e.g. `3-2`, `3-2-1`). This supports up to 3–5 levels of nesting.
+- Every annotation renders a marker showing its **local index** (the last path segment): top-level = blue water-drop with the id; nested depth 1 = purple circle; nested depth ≥2 = green triangle. A nested annotation at `3-2` is marked `2`, at `3-2-1` is marked `1` — local to its parent, not the full path.
+- To explain a UI slice that is rendered inside an annotation, nest another `<rp-annotation>` around/after it. The nested annotation gets its own numbered circle/triangle marker and its body indents one level: `main view → ⬤ annotation 3 → UI slice → ① nested annotation → detail`.
+- Clicking a pin in the main snapshot, or clicking an annotation title, updates the URL to `?section=<path>` and scrolls/focuses the matching annotation with a dashed-outline highlight.
+- Loading a URL with `?section=3-2-1` focuses that nested annotation on load (reverse deep link).
+- Each `<rp-enum-item>` is auto-numbered with a black square index badge (1, 2, 3…), so annotation prose can reference "state 2" unambiguously.
+
+Keep annotation and enum-item sibling order intentional and stable: the generated addresses depend on DOM order.
+
+
 ## Layout and state rules
 
 - RPUI is static. Do not create interactions.
@@ -71,7 +87,8 @@ RPUI renders water-drop pins automatically. Never write pin DOM manually.
 - The title/route/description and main snapshot stay visible on the left while the annotation pane scrolls independently on both axes.
 - Keep annotations compact and document-flow oriented. Do not stretch annotation content to full width.
 - Choose a device preset for new prototypes: `web` (1440px), `ipad` (834px), or `mobile` (390px). Presets use fixed width and auto height unless a numeric height is provided.
-- In the main snapshot, keep selects/dropdowns/popovers collapsed unless the page's primary representative state truly requires the overlay to be visible. Prefer showing expanded select/dropdown contents in annotation enums so they do not obscure the main layout.
+- In the main snapshot, keep selects collapsed; show their expanded list in an annotation enum.
+- Overlays and transient feedback — `rp-modal`, `rp-drawer`, `rp-dropdown`, `rp-popover`, `rp-tooltip`, `rp-toast` — are interaction results, not page regions. Do not place them in the main snapshot. Instead: pin the trigger element (button/row/field), state the trigger condition in the annotation, and render the overlay inside that annotation (usually in an `<rp-enum>`). Never stack mutually exclusive overlays/states side by side in the snapshot. A permanently docked side panel may stay open in the snapshot, but document its open/close trigger anyway.
 - Use `<rp-enum>` for state families, permission variants, hidden interaction results, and validation branches. Use `rp-enum-item description="..."` for a short clarification of a state.
 
 ## Snapshot primitives
@@ -102,7 +119,7 @@ RPUI renders water-drop pins automatically. Never write pin DOM manually.
 
 ### Data and content display
 
-- `<rp-table rows="6" columns="发件人,消息预览,时间,状态" has-checkbox has-action>` — generated static table.
+- `<rp-table rows="6" columns="发件人,消息预览,时间,状态" has-checkbox has-action>` — generated static table. Cell text is sampled by the runtime from the column names, so you cannot specify exact cell values; describe precise data in the annotation instead.
 - `<rp-table-row state="default|selected|unread|highlighted|disabled">` — standalone row slice.
 - `<rp-bulk-action-bar count="3" actions="标为已读,归档,删除">`.
 - `<rp-empty label="暂无数据" description="..." has-action>`.
@@ -135,7 +152,90 @@ All form states are explicit through attributes; there is no runtime focus or in
 
 - `<rp-alert type="info|success|warning|error" title="..." message="..." closable>`.
 - `<rp-toast type="info|success|warning|error" title="..." message="..." closable>`.
+- `<rp-banner type="info|success|warning|error" title="..." message="..." has-action closable>` — full-width page banner.
 - `<rp-progress value="40" kind="bar|circle" status="success|error">`.
+- `<rp-skeleton shape="line|block|card|list|avatar">` — loading placeholder.
+- `<rp-countdown value="02:45:18">` — time-remaining chip.
+- `<rp-result status="success|error|empty" title="..." description="..." has-action>` — full-page result.
+
+### Data input (additional)
+
+- `<rp-slider value="60" min="0" max="100" label="..." show-value>`.
+- `<rp-range low="20" high="70" min="0" max="100">` — dual-thumb range.
+- `<rp-number-input value="42">` — input with +/- steppers.
+- `<rp-rating value="3" max="5">` — star rating.
+- `<rp-pin-input length="4" value="12">` — OTP/PIN cells.
+- `<rp-color-swatch value="#2563eb" label="...">`.
+- `<rp-autocomplete value="..." placeholder="..." options="A,B,C" open>`.
+
+### Data display (additional)
+
+- `<rp-tree>` + `<rp-tree-item label="..." icon="..." level="0" expanded|collapsed state="selected">`.
+- `<rp-timeline>` + `<rp-timeline-item label="..." time="..." state="default|active|done|error">`.
+- `<rp-calendar month="2026 年 6 月" selected="15">` — month grid.
+- `<rp-kanban>` + `<rp-kanban-column title="..." count="3">` + `<rp-kanban-card label="..." tag="...">`.
+- `<rp-code-block lang="ts" lines="5">` — code placeholder with line numbers.
+- `<rp-diff rows="4">` — added/removed/context lines.
+- `<rp-image-grid count="6" columns="3">`.
+- `<rp-key-value>` + `<rp-kv-row label="..." value="...">` — description list.
+- `<rp-accordion>` + `<rp-accordion-item label="..." expanded>`.
+- `<rp-chip label="..." icon="..." closable>` — compact token.
+
+### Navigation & layout (additional)
+
+- `<rp-segmented options="日,周,月" active="1">`.
+- `<rp-menu>` + `<rp-menu-item label="..." icon="..." shortcut="⌘O" state="disabled">`.
+- `<rp-context-menu items="复制,重命名,删除">`.
+- `<rp-command-palette query="..." results="A,B,C">`.
+- `<rp-toc items="概述,安装,用法">` — table of contents.
+- `<rp-kbd keys="⌘,K">` — keyboard shortcut chips.
+- `<rp-split-pane columns="1fr 1fr">`, `<rp-divider vertical>`, `<rp-spacer size="16">`.
+
+### Enterprise / SaaS
+
+- `<rp-permission-gate reason="需管理员权限">…locked slot…</rp-permission-gate>`.
+- `<rp-quota-bar label="API 调用" used="920" limit="1000">` — turns red at ≥90%.
+- `<rp-api-key value="sk_live_••••3f9a">` — masked key with copy affordance.
+- `<rp-audit-row actor="..." action="..." time="...">`.
+- `<rp-workflow-node label="..." state="default|active|done|error">`.
+
+### iOS platform (`rp-ios-*`, use with device="mobile")
+
+- `<rp-ios-navbar title="..." large back="返回" trailing="编辑">`.
+- `<rp-ios-tabbar items="A,B,C" icons="home,search,user" active="0">`.
+- `<rp-ios-list header="...">` + `<rp-ios-list-item label="..." detail="..." icon="..." chevron>`.
+- `<rp-ios-action-sheet title="..." actions="A,B,C" destructive="删除">`.
+- `<rp-ios-alert title="..." message="..." actions="取消,确定">`.
+- `<rp-ios-switch label="...">`, `<rp-ios-segmented options="A,B" active="0">`.
+- `<rp-ios-button label="..." variant="filled|tinted|plain">`, `<rp-ios-search>`, `<rp-ios-stepper>`.
+
+### macOS platform (`rp-macos-*`, use with device="web")
+
+- `<rp-macos-window title="...">` — window chrome with traffic lights.
+- `<rp-macos-menubar items="文件,编辑,显示">`, `<rp-macos-toolbar>`.
+- `<rp-macos-sidebar>` + `<rp-macos-source-item label="..." icon="..." group state="selected">`.
+- `<rp-macos-segmented options="A,B,C" active="0">`.
+- `<rp-macos-popover title="...">`, `<rp-macos-sheet title="...">`.
+- `<rp-macos-stepper>`, `<rp-macos-disclosure label="..." expanded>`.
+- `<rp-macos-table columns="名称,大小" rows="5">` — sortable-header table look.
+
+### Agent / conversational UI
+
+For chat, copilot, and agent prototypes:
+
+- `<rp-chat>` — conversation container; wraps the message stream.
+- `<rp-user-message text="..." initials="我">` — right-aligned user bubble (text attr or rich children).
+- `<rp-assistant-message name="助手" text="...">` — left-aligned assistant message; children render as rich content (can contain tool-call/output/citation).
+- `<rp-system-message text="...">` — centered system/context note.
+- `<rp-tool-call name="search" state="running|done|error" args="...">` — tool/function call card with status.
+- `<rp-agent-output kind="text|code|terminal" label="..." text="...">` — command/code/tool output block.
+- `<rp-reasoning expanded>…</rp-reasoning>` — collapsible thinking/reasoning block.
+- `<rp-message-actions actions="copy,retry,up,down,edit,share">` — per-message action buttons.
+- `<rp-suggestions items="A,B,C">` — suggested reply / prompt chips.
+- `<rp-typing>` — streaming typing indicator.
+- `<rp-composer value="..." placeholder="..." state="idle|streaming">` — prompt input bar (send button becomes stop while streaming).
+- `<rp-citation index="1" title="...">` — source reference chip.
+- `<rp-token-usage used="1840" limit="8000">` — token/context usage meter.
 
 ## Icon rule
 
@@ -193,3 +293,6 @@ For each page, consider whether these states apply:
 </body>
 </html>
 ```
+
+For a realistic high-complexity reference (9 top-level annotations, 3–5 levels of nesting, implementation-level annotation bodies, permission matrix, state machines, SLA boundaries), see `demo/golden.html`. Refer to `SKILL.md` for the recursive decomposition method, coverage-matrix technique, and complexity expectations.
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@21stware/rpui",
-  "version": "0.1.0",
-  "description": "Readable Prototype UI: static UI prototype canvas and snapshot primitives implemented as Web Components.",
+  "version": "0.2.1",
+  "description": "Rapid Prototype UI: static UI prototype canvas and snapshot primitives implemented as Web Components.",
   "type": "module",
   "main": "dist/rpui.js",
   "module": "dist/rpui.js",
@@ -13,14 +13,15 @@
     },
     "./dist/rpui.js": "./dist/rpui.js",
     "./llms.txt": "./llms.txt",
-    "./skill.txt": "./skill.txt"
+    "./SKILL.md": "./SKILL.md"
   },
   "sideEffects": true,
   "files": [
     "dist",
     "llms.txt",
-    "skill.txt",
-    "README.md"
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "dev": "vite --open /preview/",
@@ -38,7 +39,7 @@
     "snapshot",
     "llm"
   ],
-  "license": "MIT",
+  "license": "UNLICENSED",
   "devDependencies": {
     "typescript": "^5.8.3",
     "vite": "^5.4.11"

package/skill.txt

@@ -1,143 +0,0 @@
-# RPUI Prototype Implementation Skill
-
-Use this skill when converting product requirements, screenshots, existing UI code, or design notes into a static RPUI prototype.
-
-## Goal
-
-Create one readable, static, self-contained HTML prototype that fully exposes a product page's UI structure, interaction states, permissions, loading states, empty states, error states, validation states, and edge cases.
-
-RPUI does not simulate interaction. It lays out interaction results spatially so reviewers can understand the complete state space without clicking anything. Treat it like baking time-based UI behavior into a document-flow canvas.
-
-## Required inputs
-
-Prefer these inputs, in priority order:
-
-1. Product requirement or user story.
-2. Screenshot or design draft.
-3. Existing code with conditional rendering.
-4. Permission matrix or role notes.
-5. Known loading, empty, error, validation, and edge cases.
-
-If some inputs are missing, infer common SaaS/product UI states and make assumptions explicit in annotations.
-
-## Output contract
-
-Output a complete HTML file that imports exactly one RPUI runtime file:
-
-```html
-<script type="module" src="./dist/rpui.js"></script>
-```
-
-The document must contain:
-
-1. one `<rp-page>` root with `title`, `route`, and `description`,
-2. exactly one `<rp-main-view>` containing the main page snapshot,
-3. snapshot content built with `rp-*` primitives,
-4. numbered `data-pin="N"` anchors on meaningful main-view regions,
-5. matching top-level `<rp-annotation id="N" label="...">` blocks,
-6. `<rp-enum>` and `<rp-enum-item>` blocks for conditional states and variants.
-
-## Implementation steps
-
-1. Identify the page route, page title, and one-sentence description.
-2. Choose a device preset: `web` for desktop/admin pages, `ipad` for tablet layouts, or `mobile` for phone layouts. Prefer fixed-width, auto-height prototypes.
-3. Choose the most complex representative main snapshot: loaded data, selected rows, expanded drawers/modals when they are central to the page, active validation, and role-specific controls when relevant.
-4. Build the main snapshot inside `<rp-main-view device="web|ipad|mobile">` using only `rp-*` snapshot primitives, usually inside an `<rp-viewport device="web|ipad|mobile">`.
-5. Add `data-pin="N"` to every meaningful UI region. Number pins from 1 without gaps.
-6. For every `data-pin="N"`, create one top-level `<rp-annotation id="N" label="...">`. The runtime places top-level annotations in the right-side annotation pane.
-7. Keep annotation text concise and specific. Avoid large prose blocks and card-like padding wrappers.
-8. Use nested `<rp-annotation>` only when a rule belongs to a smaller sub-region.
-9. Put repeated/conditional state families in `<rp-enum>`.
-10. Use `<rp-enum-item label="..." description="...">` for every state: default, focus, filled, selected, disabled, empty, loading, error, permission-specific, and data-size variants. `description` is optional and should be short.
-11. Validate that no interactive JavaScript, event attributes, external images, external CSS, or CDN icons are used.
-
-## Authoring rules
-
-- Use `rp-*` tags for new work. `proto-*` and `snap-*` are compatibility aliases only.
-- Use `<rp-page>`, not arbitrary root containers.
-- Use `<rp-main-view>` once per prototype page.
-- Use `rp-*` tags for both the main snapshot and UI slices inside annotations.
-- Do not use direct `div`, `button`, `input`, `table`, or similar product UI HTML. Use RPUI primitives instead. Basic text and simple inline annotation markup are allowed.
-- Do not write CSS or JavaScript in the prototype unless implementing or extending RPUI itself.
-- Do not use `position:absolute` or `position:fixed` in snapshot content. RPUI owns pin positioning.
-- Do not hide important content behind interactions. Expand it into the annotation area with `<rp-enum>`.
-- Do not stretch annotation blocks to full width. The runtime provides a right-side annotation pane; keep annotation content compact inside it.
-- Keep select/dropdown/popover overlays collapsed in the main snapshot unless visibility is essential to the representative state. Put expanded overlay contents in annotation enums or local slices so the main layout remains readable.
-- Use `rp-enum-item description="..."` for short state notes, not long prose.
-- Prefer `device="web"`, `device="ipad"`, or `device="mobile"` over hand-tuned width/height values. Use explicit numeric `height` only when a fixed-height clipped viewport is intentional.
-
-## State coverage checklist
-
-For every page, check whether these states apply:
-
-- Loaded with normal data.
-- Empty data.
-- Loading or skeleton/spinner.
-- Error or retry.
-- Search default, focus, filled, no result.
-- Filter collapsed and expanded.
-- Row default, selected, unread, highlighted, disabled.
-- Bulk selection off and on.
-- Pagination first, middle, last, no more pages.
-- Permission variants such as readonly, admin, owner, external collaborator.
-- Destructive action confirmation.
-- Validation default, filled, error, disabled.
-- Overlay states such as dropdown, popover, modal, drawer, tooltip.
-- Upload empty, has-file, uploading.
-
-## Primitive selection guide
-
-Use the smallest primitive that communicates the requirement:
-
-- page shell: `rp-page`, `rp-main-view`, `rp-viewport`
-- layout: `rp-layout`, `rp-panel`, `rp-card`
-- navigation: `rp-navbar`, `rp-sidebar`, `rp-tabs`, `rp-breadcrumb`, `rp-pagination`, `rp-steps`
-- data: `rp-table`, `rp-table-row`, `rp-list`, `rp-list-item`, `rp-stat-card`, `rp-tag`, `rp-badge`, `rp-avatar`
-- forms: `rp-input`, `rp-search`, `rp-textarea`, `rp-select`, `rp-date-picker`, `rp-checkbox`, `rp-radio`, `rp-toggle`, `rp-form`, `rp-form-item`, `rp-upload`, `rp-button`
-- states: `rp-empty`, `rp-loading`, `rp-alert`, `rp-toast`, `rp-progress`
-- overlays: `rp-dropdown`, `rp-popover`, `rp-tooltip`, `rp-modal`, `rp-drawer`
-
-Refer to `llms.txt` for the complete component attributes.
-
-## Minimal template
-
-```html
-<!doctype html>
-<html lang="zh-CN">
-<head>
-  <meta charset="UTF-8" />
-  <script type="module" src="./dist/rpui.js"></script>
-</head>
-<body>
-  <rp-page title="页面标题" route="/route" description="页面说明">
-    <rp-main-view device="web" scale="0.65">
-      <rp-viewport device="web">
-        <!-- main snapshot -->
-      </rp-viewport>
-    </rp-main-view>
-
-    <rp-annotation id="1" label="区域说明">
-      简短说明此区域的职责。
-      <rp-enum>
-        <rp-enum-item label="默认" description="正常可用的数据态。"><rp-empty label="示例"></rp-empty></rp-enum-item>
-        <rp-enum-item label="加载中" description="首次进入或刷新时展示。"><rp-loading rows="3"></rp-loading></rp-enum-item>
-        <rp-enum-item label="错误" description="服务端或网络异常时展示。"><rp-alert type="error" title="加载失败" message="请重试"></rp-alert></rp-enum-item>
-      </rp-enum>
-    </rp-annotation>
-  </rp-page>
-</body>
-</html>
-```
-
-## Quality bar
-
-A good RPUI prototype can be reviewed by engineering, product, design, and QA without running the real application. QA should be able to derive test cases from annotations. Engineering should be able to derive conditional rendering requirements from enum items. Design should be able to see whether hidden states were missed.
-
-Before finishing, check:
-
-- pin numbers are continuous and all have matching annotations,
-- the main snapshot shows the most complex useful state,
-- hidden interaction results are expanded into enums,
-- role/permission differences are visible,
-- annotations are compact and document-flow oriented,
-- no forbidden direct product UI HTML, scripts, event handlers, or external resources are present.