@llumi/design-system 0.1.0

package/README.md

@@ -0,0 +1,210 @@
+# @llumi/design-system
+
+Framework-agnostic Web Components (built with [Lit](https://lit.dev)) for the llumi
+review experience. Wrap any content in `<llumi-review>` and let users attach comments to
+whole elements or to text selections, add an overall comment, and submit an approval or a
+set of comments.
+
+- **Hybrid DOM** — your content stays in the light DOM (so text selection, `Range`s, and
+  the CSS Custom Highlight API work normally); the review chrome (toolbar, dialogs) renders
+  in Shadow DOM with its styles encapsulated.
+- **Drop-in** — works in plain HTML or any framework that can render custom elements.
+- **Per-component** — each component is imported on its own (`@llumi/design-system/review`).
+- **Three builds per component** — ESM (the default import), plus single-file UMD and IIFE
+  bundles for `<script>` / CDN use.
+
+## Installation
+
+```bash
+bun add @llumi/design-system
+# or: npm install @llumi/design-system
+```
+
+`lit` is pulled in automatically as a dependency — no peer install required.
+
+## Quick start (ESM)
+
+```ts
+// Registers <llumi-review> and all of its chrome elements.
+// The light-DOM highlight styles are injected automatically on first use —
+// no separate CSS import is required.
+import "@llumi/design-system/review";
+```
+
+```html
+<llumi-review default-mode="annotating" bar-position="bottom-center">
+  <article>
+    <h1 data-review-id="title">Project Proposal</h1>
+    <p data-review-selectable="intro">
+      Select any of this text to leave a comment on the selection…
+    </p>
+  </article>
+</llumi-review>
+
+<script type="module">
+  const review = document.querySelector("llumi-review");
+  review.addEventListener("llumi-review-submit", (e) => {
+    console.log(e.detail); // ReviewResult
+  });
+</script>
+```
+
+### `<script>` tag (no bundler)
+
+```html
+<!-- unpkg / jsDelivr both resolve the IIFE subpath via the package `exports` field -->
+<script src="https://unpkg.com/@llumi/design-system/review.js"></script>
+<!-- jsDelivr can also take the explicit file path -->
+<script src="https://cdn.jsdelivr.net/npm/@llumi/design-system/dist/review.js"></script>
+```
+
+This single file bundles Lit, registers the `<llumi-review>` element, and exposes a `Llumi`
+global. A `require()`-safe UMD/CJS build is also published at `@llumi/design-system/review.cjs`.
+
+## Marking up content
+
+Inside `<llumi-review>`, annotate the elements you want to be reviewable:
+
+| Attribute | Meaning |
+| --- | --- |
+| `data-review-id="<id>"` | A **whole-element** comment target. Clicking it (in annotate mode) opens a comment dialog and shows a badge when commented. |
+| `data-review-selectable="<id>"` | A region whose **text can be selected** to leave a selection-scoped comment. |
+
+An element may carry both attributes. The `<id>` values are yours; they are echoed back in
+each comment's `targetId`.
+
+## Component API
+
+### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `bar-position` | `top-left` \| `top-center` \| `top-right` \| `bottom-left` \| `bottom-center` \| `bottom-right` | `bottom-center` | Initial corner for the floating toolbar (which is also draggable). |
+| `shortcut` | string ([tinykeys](https://github.com/jamiebuilds/tinykeys) syntax) | `$mod+Shift+M` | Keyboard shortcut that toggles annotate mode. |
+| `default-mode` | `idle` \| `annotating` | `idle` | Whether annotate mode is on at mount. |
+
+### Properties (set in JS — complex values)
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `initialData` | `ReviewResult` | Pre-populate existing comments / overall comment. |
+| `customTargets` | `CustomTarget[]` | Resolve comment targets from arbitrary selectors (advanced). |
+
+```ts
+const review = document.querySelector("llumi-review");
+review.initialData = {
+  status: "commented",
+  comments: [{ commentId: "c1", targetId: "title", content: "Tighten this", createdAt: new Date().toISOString() }],
+};
+```
+
+### Events
+
+Both are `CustomEvent<ReviewResult>` and bubble (composed):
+
+| Event | Fires |
+| --- | --- |
+| `llumi-review-change` | On every edit (comment added/edited/deleted, overall comment changed). |
+| `llumi-review-submit` | When the user clicks Submit / Approve. |
+
+```ts
+type ReviewResult =
+  | { status: "approved" }
+  | { status: "commented"; comments: ReviewComment[]; overallComment?: string };
+
+interface ReviewComment {
+  commentId: string;
+  targetId: string;        // the data-review-id / data-review-selectable value
+  content: string;
+  createdAt: string;       // ISO timestamp
+  selection?: {            // present for text-selection comments
+    startOffset: number;
+    endOffset: number;
+    selectedText: string;
+    matchIndex: number;
+  };
+}
+```
+
+Comments in the result are ordered by their position in the document.
+
+### Keyboard shortcuts
+
+| Keys | Action |
+| --- | --- |
+| `$mod+Shift+M` (configurable) | Toggle annotate mode |
+| Hold `Alt` | Temporarily reveal all targets while held |
+| `Escape` / `$mod+Enter` | Close the open dialog |
+| `$mod+Shift+Backspace` | Delete the comment being edited |
+
+(`$mod` is ⌘ on macOS, Ctrl elsewhere.)
+
+## Custom comment editor
+
+The default editor is an auto-growing textarea. To supply your own, slot an element into
+the comment dialog's `editor` slot. Your element receives the current text via a `value`
+property and must emit these `CustomEvent`s (bubbling + composed):
+
+- `change` — `detail` is the new string value
+- `cancel` — request to close the dialog
+- `delete` — request to delete the comment
+
+```html
+<llumi-comment-dialog>
+  <my-rich-editor slot="editor"></my-rich-editor>
+</llumi-comment-dialog>
+```
+
+## Styling & customization
+
+No CSS setup is required. The chrome (toolbar, dialogs) ships its Tailwind styles inside
+each element's Shadow DOM, and the light-DOM highlight styles are injected into the
+document automatically when a `<llumi-review>` connects.
+
+To theme the highlight outlines, selection colors, and z-index, override these CSS custom
+properties. Set them on `llumi-review` (or any ancestor of your content) so they reliably
+override the injected defaults via inheritance:
+
+```css
+llumi-review {
+  /* whole-element outlines */
+  --review-highlight-commented-color: oklch(0.7 0 0 / 0.3);
+  --review-highlight-editing-color: oklch(0.6 0 0 / 0.7);
+  /* text-selection highlights */
+  --review-selection-commented-color: oklch(0.85 0.08 250 / 0.4);
+  --review-selection-editing-color: oklch(0.75 0.12 250 / 0.6);
+  --review-selection-hover-color: oklch(0.8 0.1 250 / 0.5);
+  /* stacking */
+  --review-z-index: 9998;
+}
+```
+
+All `--review-*` variables defined in the injected stylesheet are overridable this way.
+
+## Package exports
+
+| Specifier | Build |
+| --- | --- |
+| `@llumi/design-system/review` | The review component — resolves to ESM on `import`, CJS on `require` (the default entry) |
+| `@llumi/design-system/review.mjs` | ESM bundle (explicit) |
+| `@llumi/design-system/review.cjs` | UMD / CJS bundle, `require()`-safe (Lit included) |
+| `@llumi/design-system/review.js` | IIFE bundle, `Llumi` global (Lit included) |
+| `@llumi/design-system/review.css` | Light-DOM highlight styles — optional; only needed to preload them (e.g. SSR / avoid a first-paint flash), since they're otherwise auto-injected |
+
+## Known limitation
+
+Selection highlights use the document-global CSS Custom Highlight API with fixed names, so
+only one active `<llumi-review>` paints selection highlights on the page at a time (this
+matches the original React component). Whole-element highlights and everything else work
+with multiple instances.
+
+## Development
+
+```bash
+bun install
+bun run storybook        # interactive dev/docs harness
+bun test                 # logic tests (XState machine, utilities)
+bun run test:browser     # component/DOM tests (Vitest + Playwright)
+bun run build            # ESM + UMD + IIFE
+bun run ci               # full gate: lint, types, tests, manifest, build
+```