@21stware/rpui 0.2.1 → 0.3.1

package/llms.txt

@@ -1,298 +0,0 @@
-# RPUI Web Components Reference for LLMs
-
-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:
-
-```html
-<script type="module" src="./dist/rpui.js"></script>
-```
-
-`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:
-
-1. Canvas layer: page shell, main snapshot view, numbered pins, annotations, nested annotations, and state enums.
-2. Snapshot Primitive layer: static UI building blocks for product UI snapshots and annotation slices.
-
-Use `rp-*` tags for new work. Compatibility aliases are available:
-
-- `proto-*` aliases exist for canvas tags.
-- `snap-*` aliases exist for snapshot primitive tags.
-
-## Canvas tags
-
-```html
-<rp-page title="页面标题" route="/route" description="页面说明">
-  <rp-main-view device="web" scale="0.65">
-    <rp-viewport device="web">
-      <!-- fixed-width, auto-height main snapshot built with rp-* primitives -->
-    </rp-viewport>
-  </rp-main-view>
-
-  <rp-annotation id="1" label="区域说明">...</rp-annotation>
-</rp-page>
-```
-
-Tags:
-
-- `<rp-page title="..." route="..." description="...">` — root document canvas. It keeps the title/main snapshot on the left and moves top-level annotations to the right-side scroll pane.
-- `<rp-main-view device="web|ipad|mobile" width="..." height="auto|900" scale="0.65">` — scaled main snapshot frame. Device presets are fixed width with auto height unless a numeric `height` is provided.
-- `<rp-viewport device="web|ipad|mobile" width="..." height="auto|900">` — snapshot viewport. Use the same `device` as the main view for clarity.
-- `<rp-annotation id="1" label="...">` — top-level annotation linked to `data-pin="1"`; rendered in the right annotation pane.
-- `<rp-annotation label="...">` — nested annotation; no `id` required.
-- `<rp-enum>` — horizontal state/variant container.
-- `<rp-enum-item label="..." description="...">` — one explicit state/variant card with optional short description.
-
-## Pin rule
-
-Inside `<rp-main-view>`, add `data-pin="N"` to meaningful regions. Number pins from 1 without gaps.
-
-Every `data-pin="N"` must have a matching top-level annotation:
-
-```html
-<rp-navbar data-pin="1">...</rp-navbar>
-<rp-annotation id="1" label="顶部导航">...</rp-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.
-- Do not use `onclick`, hover behavior, runtime focus, timers, API calls, or framework state.
-- Do not use external images; use `<rp-image-placeholder>`.
-- Do not use `position:absolute` or `position:fixed` in snapshot content. RPUI owns pin positioning.
-- Do not use raw `div`, `button`, `input`, or `table` to represent product UI. Use `rp-*` primitives.
-- Basic text and simple inline HTML are allowed inside annotations.
-- Top-level annotations render automatically in the right-side annotation pane. Do not manually create annotation pane wrappers.
-- 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 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
-
-### Containers
-
-- `<rp-viewport device="web|ipad|mobile" width="1440" height="auto|900">` — fixed-width snapshot viewport; presets default to auto height.
-- `<rp-layout columns="260px 1fr" rows="auto" gap="16">` — CSS grid container.
-- `<rp-panel padding="24" elevation="1|2">` — white panel/card shell.
-- `<rp-card title="..." subtitle="..." has-image has-footer>` — content card.
-- `<rp-modal width="480" title="..." has-footer>` — static opened modal.
-- `<rp-drawer side="left|right" width="360" title="...">` — static opened drawer.
-- `<rp-dropdown width="300" title="...">` — static opened dropdown.
-- `<rp-popover width="300" title="...">` — static opened popover.
-- `<rp-tooltip text="..." position="top|bottom|left|right">` — visible tooltip bubble.
-
-### Navigation
-
-- `<rp-navbar height="64">` — top navigation container.
-- `<rp-sidebar width="260" collapsed>` — side navigation container.
-- `<rp-logo size="82" label="LOGO">` — logo placeholder.
-- `<rp-list items="4" state="first-selected">` — generated list when no children are provided.
-- `<rp-list-item label="..." icon="inbox" badge="12" state="default|selected|disabled">`.
-- `<rp-tabs active="0">` with `<rp-tab label="全部" badge="12">`; `active` can be index or label.
-- `<rp-breadcrumb items="首页,设置,用户管理">`.
-- `<rp-pagination total="128" current="2" page-size="20">`.
-- `<rp-steps steps="填写信息,确认,完成" active="1">`.
-
-### Data and content display
-
-- `<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>`.
-- `<rp-loading rows="4" kind="skeleton|spinner">` (`style="spinner"` also works for compatibility).
-- `<rp-image-placeholder width="160" height="100" label="Image">`.
-- `<rp-avatar size="32" initials="OC">`.
-- `<rp-badge count="120" max="99">`.
-- `<rp-tag label="已启用" color="green|orange|red" closable>`.
-- `<rp-stat-card label="活跃用户" value="12,480" trend="up|down|flat" change="+12%">`.
-
-### Forms and controls
-
-All form states are explicit through attributes; there is no runtime focus or input behavior.
-
-- `<rp-search state="default|focus|filled|error|disabled" placeholder="..." value="..." has-clear-button>`.
-- `<rp-input state="default|focus|filled|error|disabled" label="..." placeholder="..." value="..." has-clear-button error-message="...">`.
-- `<rp-textarea state="default|focus|filled|error|disabled" rows="3" placeholder="..." value="...">`.
-- `<rp-select state="collapsed|expanded|disabled" label="..." value="..." options="A,B,C">`.
-- `<rp-date-picker state="default|focus|filled|error|disabled" value="2026-06-07">`.
-- `<rp-checkbox state="unchecked|checked|indeterminate|disabled" label="...">`.
-- `<rp-radio state="unchecked|checked|disabled" label="...">`.
-- `<rp-toggle state="on|off|disabled" label="...">`.
-- `<rp-button label="..." variant="primary|secondary|ghost|danger|link" state="default|disabled|loading" icon="plus" size="sm|md|lg">`.
-- `<rp-button-group>...</rp-button-group>`.
-- `<rp-form layout="vertical|horizontal">`.
-- `<rp-form-item label="..." required error="...">...</rp-form-item>`.
-- `<rp-upload state="empty|has-file|uploading" file="document.pdf" progress="60">`.
-
-### Feedback
-
-- `<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
-
-Use Lucide icon names through the `icon` attribute when available:
-
-```html
-<rp-button label="新建" icon="plus" variant="primary"></rp-button>
-<rp-list-item label="已归档" icon="archive"></rp-list-item>
-```
-
-The runtime renders inline SVG. Do not import lucide or any icon CDN.
-
-## State coverage checklist
-
-For each page, consider whether these states apply:
-
-- loaded with normal data
-- empty data
-- loading/skeleton/spinner
-- error/retry
-- search default/focus/filled/no-result
-- filter collapsed/expanded
-- row default/selected/unread/highlighted/disabled
-- bulk selection off/on
-- pagination first/middle/last/no more pages
-- permission variants: readonly/admin/owner/external collaborator
-- destructive confirmation
-- validation default/filled/error/disabled
-
-## Recommended complete HTML shape
-
-```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 built only with rp-* primitives -->
-      </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>
-    </rp-annotation>
-  </rp-page>
-</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.
-